docs: Update PSScript examples#1528
Conversation
There was a problem hiding this comment.
Pull request overview
This PR refreshes and expands the documentation examples for the transitional PowerShellScript and WindowsPowerShellScript DSC resources, aligning the resource reference pages with clearer, more complete sample scenarios.
Changes:
- Update resource index pages to point to the new/renamed example documents.
- Add a new
WindowsPowerShellScriptexample showing get/test/set patterns for Windows service state. - Add two new
PowerShellScriptexamples covering basic get/set/test behavior and input/output binding patterns.
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/reference/resources/Microsoft/DSC/Transitional/WindowsPowerShellScript/index.md | Updates the “See also” example link to the new Windows service-state example page. |
| docs/reference/resources/Microsoft/DSC/Transitional/WindowsPowerShellScript/examples/manage-windows-service-state-with-powershell.md | New end-to-end example demonstrating inline Windows PowerShell scripts for service state management. |
| docs/reference/resources/Microsoft/DSC/Transitional/PowerShellScript/index.md | Updates the example link to the renamed “run a simple” example page. |
| docs/reference/resources/Microsoft/DSC/Transitional/PowerShellScript/examples/run-a-simple-powershell-script.md | New example illustrating basic get/set/test usage and stream/log-level mapping. |
| docs/reference/resources/Microsoft/DSC/Transitional/PowerShellScript/examples/powershell-script-with-input-output.md | New example illustrating input binding and error cases when input/param mismatch. |
|
Starting editorial pass, will be updating the commit directly and force pushing when completed. Please don't make any changes to this PR while I'm actively editing the documentation. Thank you! |
michaeltlombardi
force-pushed
the
update-ps-examples
branch
2 times, most recently
from
f23e8d4 to
da95e53
Compare
This change updates the reference docs for the `WindowsPowerShellScript` resource, including new examples and updates to the index page. It is largely a mirror of the `PowerShellScript` resource, as the resources share an implementation script.
michaeltlombardi
force-pushed
the
update-ps-examples
branch
from
da95e53 to
65b9a48
Compare
|
Approved, pending final technical review - should only need to review one set of docs, as the content is largely mirrored across them. |
|
@SteveL-MSFT - mind doing a technical review on this one? |
|
|
||
| These examples show how you can pass input data to the | ||
| [`Microsoft.DSC.Transitional/PowerShellScript` resource][01] and how to bind that data to your | ||
| script with a [`param()` statement][02]. |
There was a problem hiding this comment.
I wonder if it's worth expanding that the script should NOT use $input as the script param name since that's reserved for PowerShell and that the param name can be whatever the user wants, but there can only be one param for the script.
| The first error in the output indicates that the script execution was stopped by the error from the | ||
| `Get-Command` invocation, which showed that `tstoy` wasn't available on the system. | ||
|
|
||
| ### Emitting errors with `Write-Error` |
There was a problem hiding this comment.
I would call out that the default is $ErrorActionPreference = 'Stop'
| Write-Error "command 'tstoy' not found; unable to report version for 'tstoy'" | ||
| } | ||
|
|
||
| & $tstoyCmd version --full --format json | ConvertFrom-Json |
There was a problem hiding this comment.
It might be worth stating that when using native commands, the script author needs to explicitly check $LASTEXITCODE as that won't automatically cause a failure unless they use https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_preference_variables?view=powershell-7.6#psnativecommanduseerroractionpreference with PS7
PR Summary
This pull request updates the already scaffolded examples for
Microsoft.DSC.Transitional/WindowsPowerShellandMicrosoft.DSC.Transitional/PowerShell.